feat: Add optional exponential backoff for polling interval (#99) by mem-5514-tahara · Pull Request #139 · OutdatedGuy/internet_connection_checker_plus

mem-5514-tahara · 2026-06-05T11:07:33Z

Hi @OutdatedGuy! Thanks for maintaining this awesome package.

Closes #99

Problem

The onStatusChange polling loop retries at a fixed checkInterval (default 10 s) regardless of connection state. During extended outages this results in unnecessary battery drain, wasted CPU cycles, and pointless network traffic on mobile devices.

Analysis

Inspecting _maybeEmitStatusUpdate() in lib/src/internet_connection.dart confirmed the timer is always rescheduled with the same _checkInterval:

_maybeEmitStatusUpdate()
  └─ await internetStatus
  └─ if status changed → emit
  └─ Timer(_checkInterval, _maybeEmitStatusUpdate)  // always the same value

Key design constraints identified before implementation:

_lastStatus is mutated inside _maybeEmitStatusUpdate, so distinguishing "first failure" from "ongoing failure" requires snapshotting its value before the update.
All new parameters must default to "backoff disabled" (useExponentialBackoff = false) to leave the singleton InternetConnection() and existing callers completely unaffected.
Backoff state must reset on reconnect, on setIntervalAndResetTimer(), and on last-listener cancel.
When backoffInitialDelay is not explicitly provided, it should track _checkInterval so a setIntervalAndResetTimer() call does not leave a stale initial delay from construction time.

Changes

Files modified:

lib/src/internet_connection.dart
test/internet_connection_test.dart

New `createInstance` parameters

Parameter	Type	Default	Description
`useExponentialBackoff`	`bool`	`false`	Opt-in flag; `false` preserves existing behaviour exactly
`backoffInitialDelay`	`Duration?`	same as `checkInterval`	Delay applied after the first failure
`backoffMaxDelay`	`Duration`	`Duration(seconds: 60)`	Upper bound on the retry interval
`backoffMultiplier`	`double`	`2.0`	Factor applied to the delay on each consecutive failure

Backoff logic

first failure    → nextDelay = backoffInitialDelay
ongoing failure  → nextDelay = min(currentDelay × multiplier, maxDelay)
reconnect        → nextDelay = checkInterval  (reset)

previousStatus is snapshotted before the _lastStatus mutation so that the branch correctly identifies the first failure even when previousStatus is null (very first poll):

final previousStatus = _lastStatus;  // snapshot before mutation

// ... _lastStatus update ...

if (useExponentialBackoff) {
  if (currentStatus == InternetStatus.connected) {
    _currentBackoffDelay = _backoffInitialDelay;
    nextDelay = _checkInterval;
  } else if (previousStatus != InternetStatus.disconnected) {
    // First failure: previousStatus is null (initial poll) or connected.
    _currentBackoffDelay = _backoffInitialDelay;
    nextDelay = _currentBackoffDelay;
  } else {
    // Ongoing failure: grow the delay.
    final ms = (_currentBackoffDelay.inMilliseconds * _backoffMultiplier).round();
    _currentBackoffDelay = Duration(
      milliseconds: ms.clamp(0, _backoffMaxDelay.inMilliseconds).toInt(),
    );
    nextDelay = _currentBackoffDelay;
  }
}

.toInt() is appended to .clamp() as a defensive cast: ms is int in current Dart, but num.clamp can return num depending on the Dart version or analyzer strictness, which would cause a type error on the milliseconds: field.

Backoff state reset conditions

Trigger	Behaviour
`currentStatus == connected`	Reset `_currentBackoffDelay` to `_backoffInitialDelay`
`setIntervalAndResetTimer(duration)`	If `backoffInitialDelay` was not explicitly provided, also update `_backoffInitialDelay` to `duration` before resetting `_currentBackoffDelay`; otherwise keep the caller-specified value
Last listener cancelled (`_handleStatusChangeCancel`)	Reset `_currentBackoffDelay` to `_backoffInitialDelay` so the next subscription starts clean

The backoffInitialDelay tracking is implemented with a final bool _backoffInitialDelayExplicit flag set in the initializer list. When false, _backoffInitialDelay is updated in setIntervalAndResetTimer to stay in sync with _checkInterval, preventing a stale initial delay from lingering after the interval is changed dynamically.

Usage example

final connection = InternetConnection.createInstance(
  checkInterval: const Duration(seconds: 10),
  useExponentialBackoff: true,
  backoffInitialDelay: const Duration(seconds: 10),
  backoffMaxDelay: const Duration(minutes: 1),
  backoffMultiplier: 2.0,
);
// Retry delays on failure: 10s → 20s → 40s → 60s → 60s → ...
// Resets to 10s immediately on reconnect.

Tests

Added group('exponentialBackoff', ...) to test/internet_connection_test.dart. Tests use customConnectivityCheck with DateTime.now() call logging to avoid real network calls and enable deterministic timing assertions.

Test case	What it verifies
disabled by default	Fixed interval is preserved with backoff off (regression guard)
first failure sets initialDelay	`backoffInitialDelay` is used on the first disconnect
delay grows on consecutive failures	Gaps between calls are monotonically non-decreasing
delay is capped at maxDelay	No gap exceeds `backoffMaxDelay`
delay resets to checkInterval on reconnect	Interval reverts to `checkInterval` after reconnect
setIntervalAndResetTimer resets backoff	Backoff sequence restarts from `backoffInitialDelay` after interval change
re-subscription resets backoff	Cancel + re-listen starts the backoff sequence from the beginning
first poll returning disconnected	`previousStatus == null` is treated as first failure, not ongoing

dart test              →  30/30 passed
dart analyze lib/ test/ →  No issues found

When `useExponentialBackoff` is enabled, the retry interval grows exponentially on consecutive failures and resets to `checkInterval` on reconnect, reducing unnecessary battery drain and network traffic during prolonged outages. New `createInstance` parameters: - `useExponentialBackoff` (bool, default false) - `backoffInitialDelay` (Duration?, default: checkInterval) - `backoffMaxDelay` (Duration, default: 60s) - `backoffMultiplier` (double, default: 2.0) Closes OutdatedGuy#99

Copilot

Pull request overview

Adds an opt-in exponential backoff strategy to the InternetConnection.createInstance polling loop to reduce polling frequency during extended disconnects (while preserving existing behavior by default), and extends the test suite to cover the new timing behavior.

Changes:

Introduces useExponentialBackoff and related backoff configuration parameters on InternetConnection.createInstance.
Implements adaptive timer rescheduling in _maybeEmitStatusUpdate() based on connection status and backoff state.
Adds a new exponentialBackoff test group to validate backoff growth, capping, and reset behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
`lib/src/internet_connection.dart`	Adds backoff configuration/state and uses it to compute the next polling delay.
`test/internet_connection_test.dart`	Adds tests intended to validate backoff timing and reset behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

As pointed out by Copilot, calling `setIntervalAndResetTimer` while already disconnected would cause the next poll to be treated as an ongoing failure (immediately multiplying the delay) because `previousStatus` remained disconnected. This commit introduces a `_backoffNeedsReset` flag to force the next poll to be treated as a "first failure" without mutating `_lastStatus` (which would have caused duplicate disconnected events). Also includes a new test to verify implicit initial delay synchronization.

- Update assertion for `backoffMultiplier` to require a value >= 1.0. Values between 0 and 1 would cause the polling delay to decay toward 0ms, leading to a tight polling loop during an outage.

- Add assertions to ensure `backoffInitialDelay` (or its fallback `checkInterval`) is greater than zero to prevent immediate/negative timer loops. - Add assertion to ensure `backoffInitialDelay` is less than or equal to `backoffMaxDelay`, keeping the backoff sequence logically sound and preventing the delay from shrinking on the second poll.

…y on first failure

Replace always-true expect(sub, isNotNull) with real behavioral checks: verify call count (~4-5 in 550ms) and that consecutive gaps stay under 200ms, catching regressions where backoff activates unintentionally.

mem-5514-tahara · 2026-06-08T20:25:37Z

Hi @OutdatedGuy! I’ve addressed the issues GitHub Copilot flagged, so could you please take another look at my proposal?

OutdatedGuy · 2026-06-09T08:50:34Z

@mem-5514-tahara can you disclose if this PR heavily AI generated or just AI assisted?

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

mem-5514-tahara · 2026-06-09T16:24:19Z

@OutdatedGuy
Thanks for asking! I would classify it as AI-assisted.

I used Claude Code to help investigate the issue and draft the initial logic and tests. I manually guided the design decisions (such as keeping strict backward compatibility) and reviewed the code, but I definitely missed a few things—as Copilot just rightly pointed out with that race condition during cancellation! 😅

I'm taking full responsibility for the code. I will apply Copilot's suggested fixes (the race condition check and dart format) and push them right away. Please let me know if you spot anything else!

Re-check hasListener immediately before scheduling the next timer so that a cancel arriving during the await internetStatus suspension does not restart polling with zero listeners.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

… builds Replace assert()-only guards with ArgumentError throws so that invalid backoff parameters (multiplier < 1.0, zero delays, initialDelay > maxDelay) are caught in release/AOT builds, not just debug mode.

Introduce a monotonically-increasing `_generation` counter that is bumped on every reschedule (setIntervalAndResetTimer) and on cancel (_handleStatusChangeCancel). Each _maybeEmitStatusUpdate invocation captures the counter on entry and bails out before mutating _currentBackoffDelay / _backoffNeedsReset if the value has changed, preventing a stale callback from silently overwriting the reset that the newer owner already applied.

… initial delay computation

…scribers Introduce _cancelGeneration, bumped only on _handleStatusChangeCancel, to distinguish cancel+resubscribe cycles from setIntervalAndResetTimer calls. _maybeEmitStatusUpdate now snapshots _cancelGeneration before the async gap and skips the emit if a mismatch is detected, ensuring the new subscriber receives only its own fresh check result. Also fix the doc example (await listener.cancel()), document the intentionally unawaited _triggerSubscription?.cancel(), and add three tests: initial-yield caching, setIntervalAndResetTimer during connected period, and the stale-emit regression.

OutdatedGuy · 2026-06-16T05:26:12Z

@mem-5514-tahara thanks for the disclosure. I'm gonna need a lot of time to verify if this PR doesn't add any regressions or bugs due the experiences I have had using AI to maintain this package.

I'll look into this PR in July as my copilot reviews have exhausted for this month. Thanks for the PR.

OutdatedGuy · 2026-07-15T09:44:34Z

@mem-5514-tahara can you resolve the merge conflicts? I'll request co-pilot review after you resolve them.

# Conflicts: # lib/src/internet_connection.dart # test/internet_connection_test.dart

mem-5514-tahara · 2026-07-15T10:17:18Z

Hi @OutdatedGuy,

I have resolved the merge conflicts!
Please take a look and trigger the Copilot review when you are ready. Thank you!

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

mem-5514-tahara · 2026-07-20T23:48:58Z

        ) {
+    if (useExponentialBackoff) {


fix: address PR review feedback for exponential backoff

mem-5514-tahara · 2026-07-20T23:49:07Z

+        expect(received, [InternetStatus.connected]);
+
+        await sub1.cancel();
+        await sub2.cancel();
+      });


fix: address PR review feedback for exponential backoff

mem-5514-tahara · 2026-07-20T23:49:13Z

+        final option =
+            InternetCheckOption(uri: Uri.parse('https://example.com'));
+        return InternetConnection.createInstance(
+          checkInterval: checkInterval,
+          useDefaultOptions: false,
+          customCheckOptions: [option],
+          useExponentialBackoff: true,
+          backoffInitialDelay: backoffInitialDelay,
+          backoffMaxDelay: backoffMaxDelay,
+          backoffMultiplier: backoffMultiplier,
+          customConnectivityCheck: (opt) async {
+            callLog.add(DateTime.now());
+            return InternetCheckResult(option: opt, isSuccess: shouldSucceed());
+          },
+        );
+      }


fix: address PR review feedback for exponential backoff

Validate useDefaultOptions/customCheckOptions with a runtime ArgumentError instead of assert, since asserts are stripped in release builds and would otherwise leave hasInternetAccess awaiting forever on an empty options list. Also dispose InternetConnection instances in tests to avoid leaking HTTP clients and stream controllers across test runs.

NaN and Infinity both satisfy `!(x < 1.0)`, so the multiplier validation let them through the constructor only to throw an uncaught UnsupportedError from round() once the delay started growing on a second consecutive failure. Also documents the four new backoff constructor parameters and adds public getters (backoffInitialDelay, backoffMaxDelay, backoffMultiplier, currentBackoffDelay) so callers can introspect the effective backoff state.

mem-5514-tahara · 2026-07-20T23:58:36Z

Hi @OutdatedGuy,

I've addressed all the Copilot review feedback from the previous rounds (asserts → ArgumentError, backoff reset timing, the generation guard against stale timers, test disposal/formatting, etc.) — replies are inline on each corresponding thread.

While going back through the backoff validation logic once more, I found one more edge case Copilot's earlier review didn't flag: backoffMultiplier < 1.0 is false for both double.nan and double.infinity (IEEE-754 comparison semantics), so either value slips past the constructor's validation. It then throws an uncaught UnsupportedError later, inside the polling Timer callback, the first time the delay needs to grow ((delay * multiplier).round() on NaN/Infinity) — i.e. a caller passing a bad multiplier gets a deferred crash instead of an immediate, catchable ArgumentError at construction time.

Fixed in 479a19f, which also:

Adds two regression tests (NaN / Infinity multiplier → ArgumentError at construction).
Documents the four new createInstance backoff parameters on the constructor itself (previously only described in the PR body, not in code).
Adds public getters (backoffInitialDelay, backoffMaxDelay, backoffMultiplier, currentBackoffDelay) so callers can introspect the effective backoff config and current retry delay, e.g. for "retrying in Xs" UI.

dart format, dart analyze, and the full test suite (32/32) are all green with this change included. Let me know if you'd like anything adjusted.

OutdatedGuy requested a review from Copilot June 6, 2026 10:23

Copilot started reviewing on behalf of OutdatedGuy June 6, 2026 10:23 View session

Copilot AI reviewed Jun 6, 2026

View reviewed changes

Comment thread lib/src/internet_connection.dart

Comment thread lib/src/internet_connection.dart Outdated

Comment thread lib/src/internet_connection.dart Outdated

Comment thread lib/src/internet_connection.dart Outdated

Comment thread test/internet_connection_test.dart Outdated

mem-5514-tahara added 3 commits June 8, 2026 18:32

fix: prevent shrinking backoff intervals

8db4023

- Update assertion for `backoffMultiplier` to require a value >= 1.0. Values between 0 and 1 would cause the polling delay to decay toward 0ms, leading to a tight polling loop during an outage.

Repository owner locked and limited conversation to collaborators Jun 8, 2026

Repository owner unlocked this conversation Jun 8, 2026

mem-5514-tahara added 3 commits June 9, 2026 04:07

test(exponential-backoff): add constructor validation tests

4c01cbc

fix(exponential-backoff): cap initial backoff delay to backoffMaxDela…

dc88a70

…y on first failure

test(exponential-backoff): strengthen fixed-interval assertion

e4b6d30

Replace always-true expect(sub, isNotNull) with real behavioral checks: verify call count (~4-5 in 550ms) and that consecutive gaps stay under 200ms, catching regressions where backoff activates unintentionally.

OutdatedGuy requested a review from Copilot June 9, 2026 08:50

Copilot started reviewing on behalf of OutdatedGuy June 9, 2026 08:50 View session

Copilot AI reviewed Jun 9, 2026

View reviewed changes

Comment thread lib/src/internet_connection.dart

Comment thread test/internet_connection_test.dart Outdated

mem-5514-tahara added 2 commits June 10, 2026 01:27

fix(polling): guard timer reschedule against cancelled listeners

ea96ec3

Re-check hasListener immediately before scheduling the next timer so that a cancel arriving during the await internetStatus suspension does not restart polling with zero listeners.

style: apply dart format to lib and test

f820496

mem-5514-tahara requested review from Copilot June 9, 2026 16:37

Copilot AI reviewed Jun 9, 2026

View reviewed changes

Comment thread lib/src/internet_connection.dart Outdated

Comment thread lib/src/internet_connection.dart

Comment thread lib/src/internet_connection.dart Outdated

Comment thread test/internet_connection_test.dart Outdated

Comment thread test/internet_connection_test.dart

mem-5514-tahara added 4 commits June 10, 2026 01:43

fix(exponential-backoff): enforce backoff param validation in release…

6c655ae

… builds Replace assert()-only guards with ArgumentError throws so that invalid backoff parameters (multiplier < 1.0, zero delays, initialDelay > maxDelay) are caught in release/AOT builds, not just debug mode.

refactor(exponential-backoff): extract _resolveInitialDelay to DRY up…

2aed826

… initial delay computation

Merge remote-tracking branch 'origin/main' into feat/exponential-backoff

83b016e

# Conflicts: # lib/src/internet_connection.dart # test/internet_connection_test.dart

OutdatedGuy requested review from Copilot and removed request for Copilot July 20, 2026 13:14

Copilot started reviewing on behalf of OutdatedGuy July 20, 2026 13:14 View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

mem-5514-tahara added 2 commits July 21, 2026 06:07

Uh oh!

Conversation

mem-5514-tahara commented Jun 5, 2026

Problem

Analysis

Changes

New createInstance parameters

Backoff logic

Backoff state reset conditions

Usage example

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mem-5514-tahara commented Jun 8, 2026

Uh oh!

OutdatedGuy commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

mem-5514-tahara commented Jun 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

OutdatedGuy commented Jun 16, 2026

Uh oh!

OutdatedGuy commented Jul 15, 2026

Uh oh!

mem-5514-tahara commented Jul 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mem-5514-tahara Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

mem-5514-tahara Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

mem-5514-tahara Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

mem-5514-tahara commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

New `createInstance` parameters

OutdatedGuy commented Jun 9, 2026 •

edited

Loading

mem-5514-tahara commented Jul 20, 2026 •

edited

Loading